% LATEX Documentation for CForms
% By Lars Berntzon
% @(#) cforms.tex,v 1.10 1993/07/21 00:02:44 lasse Exp
%
\newcommand{\synopsys}[1]{\verb!\newline
Synopsys: {#1}!
}

\documentstyle{article}
\title{CForms v
\input patchlevel
}
\author{Lars Berntzon, E-Mail: lab@cap.se}
\begin{document}
\maketitle

\section{Introduction}

	CForms is a formular manager for building applications to be used for
	many types of terminals though it uses the {\em curses} library.
	CForms is built up by a language that consists of the objects: modules,
	pictures, fields, literals and events. This language is the compiled
	with a compiler called {\em cfc} an all compiled files are finally
	linked with a linker called {\em cfl}.

	An application is built by one or more modules that contains one or more
	pictures that handles the various functions in the application.
	Each picture may contain any number of fields and text literal
	that describes the appearance of the picture.

	Fields are defined by their name and are shaped by their type,
	size, special attributes and event handling functions.

	CForms may be intermixed with C-code modules in any way.


\section{Language description}

	The language is not case sensitive exept thoose parts
	that are pure C-code (in events- and ccode statements).

	
\subsection{Viewports}

	To create a picture you first need to create a viewport, wich 
	describes the size and position on the real screen where the picture
	should appear. A viewport is defined by its name, wich later should
	be referenced by the picture. Several pictures may share the same
	viewport.

	Syntax for a viewport is:
	\begin{verbatim}
        VIEWPORT <name> {
            POS <column>, <row>;
            SIZE <width>, <height>;
        }
	\end{verbatim}

	Example:
	\begin{verbatim}
        Viewport stdscreen {
            Pos 1,1;
            Size 80, 24;
        }
	\end{verbatim}


\subsection{CCode}
	The CCode statement introduces a C-code block that may contain any
	code such as global variables, functions, preprocessor statements.
	This means that there is no need to have separated form-files and
	C-files with support functions. Ccodes may only be used in outer
	scopes, i.e. not inside pictures, literals or fields.

	Syntax for Ccode is:
        \begin{verbatim}
        CCODE {
            <Any C code>
        }
        \end{verbatim}

	Example:
        \begin{verbatim}
        CCode {
            cleanup()
            {
                free_all_mem();
                cforms_end();
                exit();
            }
        }
        \end{verbatim}


\subsection{Pictures}

	A picture is what shows up on the terminal when the application is
	running. Pictures contains fields - which are places for input or
	output, literals - which are static texts and events -
	events doesn't show but defines C-code functions to be called when
	certain things happens. Events specified in pictures are actually
	used by fields, but they are automatically specified for all fields
	in that pictures (unless specifically turned off), in other worlds a
	default event for all fields.

	A pictures is defined by its name, and the first picture to be started
	in the application is determined in the main routine (or a descendant)
	through the function {\em pic\_call}.

	A picture can also have modifiers, currently the only modifier available
	is the word {\em Frame} will cause a border to be drawn around the
	picture, note that this will scrink the effective area of the picture.

	Syntax for a picture is:
	\begin{verbatim}
        PICTURE <picture-name> VIEWPORT <viewport-name> {
            <literals>   \
            <fields>      > in any order
            <modifier>   |
            <events>     /
        }
	\end{verbatim}

	Example:
	\begin{verbatim}
        Picture main Viewport stdscreen {
            Literal 10, 10, "Welcome, enter your name: ";
            Frame;
            Field Name {
                Pos +0, +1;
                Type Char(10);
            }
        }
	\end{verbatim}


\subsection{Fields}

	Fields are placesholders in pictures that may be used to input from
	operator and/or as output from the application. A field may be of
	many kind of types and sizes. Fields can also contain events that
	will be called when the specified event occurs. It is also possible
	to specify literal text to appear immediately before and immediately
	after the actual field, this makes it possible to have text belonging
	to fields that are not depending of the fields position.

	The position of a field may be specified in absolute- or relative 
	coordinates. For relative coordinates the column- and row number is
	prefixed by a minus or a plus sign meaning positive or negative
	relative position. A position can also be specified as {\em Center}
	as either the row or column value which will center the field and the
	word {\em Max} wich will place the field at the border of the picture
	(rightmost column or lowest line).
	Finally it is possible to specify a couple of modifiers for the field
	that modifies adjustment, visibility, protection e.t.c.


	Valid types for a field is:
	\begin{itemize}
	   \item{INT} Field may only contain digits.
	   \item{ALNUM} Field may only contain alphanumeric characters.
	   \item{CHAR} Field may contain any printable character.
	\end{itemize}
	The size of a field is by default 1, but may be altered as a number
	within brackets after the type.

	Valid modifiers are:
	\begin{itemize}
	    \item{PROTECTED}	- Field may not be altered.
	    \item{FORBIDDEN}	- Field may not be be moved to.
	    \item{UPPERCASE}	- All alpha characters are in uppercase.
	    \item{HIGHLIGHT}	- Field is highlighted.
	    \item{INVISIBLE}	- Field is invisible.
	\end{itemize}

	Syntax for a field is:
	\begin{verbatim}
        FIELD <name> {
            <type> [(<size>)];
            POS [+-]<column>, [+-]<row>;
            LVALUE "<left value>";
            RVALUE "<right value>";
            [MODIFIER;]
        }
	\end{verbatim}
	Example:
	\begin{verbatim}
        Field adress {
            Pos 20, +1;
            Type Char(20);
            LValue "Adress: ";
            Uppercase;
        }
	\end{verbatim}

\subsection{Literals}

	Literals is static text to be visualized in the picture, literals
	is below fields if a collission should occur. The same position
	coordinates can be used as for fields (ex. Center).
	Syntax of a literal is:
	\begin{verbatim}
        Literal [+-]<column>, [+-]<row>, "<text>";
	\end{verbatim}
	Example:
	\begin{verbatim}
        Literal +0, +1, "List of persons";
	\end{verbatim}

\subsection{Events}

	Events are used to define functions keys and other special cases for eg.
	refresh display and so on. An event is specified by its event type
	and either a block of C-code to execute when the event occurres, or the
	word 'forget' wich means that the specified event should be disabled for
	this field.

	Type of events is:
	\begin{itemize}
	   \item[KEY] A key has been pressed. An event of the type KEY must 
		      be followed by the name of the key, later in this
		      document you will find a list of all valid keys. The
		      special key ANY means any key and the variable
		      {\em event\_code} contains the value of that key.
	   \item[REFRESH] Refresh the picture.
	   \item[DRAW] Only available from pictures, is called.
	    	       when a pictures is first drawn.
	   \item[ENTRY] When field is entered.
	   \item[EXIT] When field is left.
	   \item[PREVIOUS] When trying to move to the left of the field.
	   \item[NEXT] When trying to move to the right of the field.
	\end{itemize}
	    

	Syntax for an event is:
	\begin{verbatim}
        [GLOBAL] EVENT <type> [<type modifier>] {
            <C-code statements>
        }
	\end{verbatim}
	or
	\begin{verbatim}
        [GLOBAL] EVENT <type> [<type modifier>] FORGET;
	\end{verbatim}
	Example:
	\begin{verbatim}
        Event Entry {
            fld_set(NULL, "X");
        }

        Event Key DOWN  {
            fld_move(fld_down(NULL));
        }
	\end{verbatim}

	The keywork {\em GLOBAL} may only be specified for events outside
	fields and pictures and if it is this event handler will be active 
	for all pictures in the application unless overridden by more local
	event handlers including the {\em FORGET} type.

	
\section{EVENT and CCODE programing}


	For all event- and ccode blocks the developer can use a set
	library functions that comes with cforms. Most functions returning
	integers returns either OK or FAIL exept for those like fld\_len that
	returns the value expected. Those returning pointers return NULL
	uppon failure.
	This is a list and a description of all functions:	    
	\subsection{Start/stop functions}
 	    \subsubsection{cforms\_init} Initiate CForms, this must be done
		before any cforms functions can be called.
	        \synopsys{int cforms\_init(void)}

	    \subsubsection{cforms\_end} Stop CForms.
		\synopsys{int cforms\_end(void)}

	    \subsubsection{cforms\_refresh} Refresh the CForms screen.
		\synopsys{void cforms\_system(void)}

	    \subsubsection{cforms\_system} Run a operating system command.
		\synopsys{int cforms\_system(const char *command, const char *prompt)} \\
		This will run a operating system command without destroying
		the screen. Before the command is executed the screen is cleared
		and upon completion the screen will be redrawn. If the
		{\em prompt} is not NULL then the routine will also print the
		prompt and waint until user presses the return key.

 	\subsection{Picture functions}
 	    \subsubsection{pic\_call} Call picture.
	       \synopsys{int pic\_call(struct picture *, field *)}\\
		Where picture is a pointer to the picture to call and field
		is where the cursor lands on, NULL means the first field in
		picture.

	    \subsubsection{pic\_clear} Clear all fields for picture.
		\synopsys{int pic\_clear(struct picture *)}\\
		If picture is NULL current picture is cleared.

	    \subsubsection{pic\_leave} Leave current picture after current
		event has finished.
		\synopsys{int pic\_leave(void)}

	    \subsubsection{picture} Get picture with name.
		\synopsys{struct picture *picture(char *fmt, ...)}\\
		Returns a pointer to a picture with the name generated
		with 'fmt' and its arguments the same way that printf works.

	\subsection{Field functions}
	    \subsubsection{field} Get field with name
		\synopsys{struct field *field(char *fmt, ...)}\\
		Returns a pointer to a field with the name generated
		with 'fmt' and its arguments the same way that printf works.

		If the field name is prepended by the picture name and a
		colon, i.e.  "picture:field", a field can be found in another
		picture than current picture.
		
	    \subsubsection{fld\_isempty} Check if field is empty, i.e.
		full of spaces, tabs or null.
		\synopsys{int fld\_isempty(struct field *)}\\
		Returns TRUE or FALSE condition.

	    \subsubsection{fld\_first} Find first field of picture.
		\synopsys{struct field *fld\_first(void)}

	    \subsubsection{fld\_last} Find last field of picture.
		\synopsys{struct field *fld\_last(void)}

	    \subsubsection{fld\_next} Find next field for picture.
		\synopsys{struct field *fld\_next(struct field *)}\\
		Returns the field after field given by argument (or
		current field if NULL).
		
	    \subsubsection{fld\_previous} Find previous field for picture.
		\synopsys{struct field *fld\_previous(struct field *)}\\
		Returns the field berfore field given by argument (or
		current field if NULL).

	    \subsubsection{fld\_left} Find left field.
		\synopsys{struct field *fld\_left(struct field *)}\\
		Returns the field to the left of the field given by argument
		(or current field if NULL).

	    \subsubsection{fld\_right} Find right field.
		\synopsys{struct field *fld\_right(struct field *)}\\
		Returns the field to the right of the field given by argument
		(or current field if NULL).

	    \subsubsection{fld\_up} Find field above current.
		\synopsys{struct field *fld\_up(struct field *)}\\
		Returns the field above the field given by argument
		(or cur\-rent.\-field if\- NULL).

	    \subsubsection{fld\_down} Find field below current.
		\synopsys{struct field *fld\_down(struct field *)}\\
		Returns the field below the field given by argument
		(or current \-field if\- NULL).

	    \subsubsection{fld\_set} Set value for field.
		\synopsys{int fld\_set(struct field *, char *)}\\
		If field is NULL set value for current field.

	    \subsubsection{fld\_nset} Set value for field but max n chars.
		\synopsys{int fld\_nset(struct field *, char *)}\\
		If field is NULL set value for current.field.

	    \subsubsection{fld\_get} Get value of field.
		\synopsys{char *fld\_get(struct field *)}\\
		If field is NULL get value for current field.

	    \subsubsection{fld\_get\_trimmed} Get value of field with trimmed blanks.
		\synopsys{char *fld\_get(struct field *)}\\
		This routine works like {\em fld\_get} exept that leading and trailing blanks
		is removed in the returned string.
		If field is NULL get value for current field.

	    \subsubsection{fld\_len} Return length of field.
		\synopsys{int fld\_len(struct field *)}\\
		If field is NULL return length for current field.
		
	    \subsubsection{fld\_name} Return name of a field.
		\synopsys{char *fld\_name(struct field *)}\\
		If field is NULL return name of current field.
		
	    \subsubsection{fld\_ismodified} Return true if field has been
		modified since last fld\_set or fld\_nset.
		\synopsys{int fld\_ismodified(struct field *)}\\
		If field is NULL return modified for current field.
		
	    \subsubsection{fld\_touch} Make field not modified.
		\synopsys{int fld\_touch(struct field *)}\\
		If field is NULL touch current field.

	    \subsubsection{fld\_sattr} Set attributed for a field.
		\synopsys{int fld\_sattr(struct field *, unsigned long)}\\
		The attributes are only added to the field, to remove attributes
		one must use {\em fld\_cattr()}.
		If field is NULL use current field.
		Possible attributes are:
		\begin{itemize}
		\item[FLD\_HIGHLIGHT] - Turn on highlighting of field.
		\item[FLD\_PROTECTED] - Make field insensitive for input.
		\item[FLD\_FORBIDDEN] - Make field illegal to move to. If the field modified is current field 
					then result is undefined.
		\item[FLD\_INVISIBLE] - Make field invisible.
		\end{itemize}

            \subsubsection{fld\_cattr} Clear attributed for a field.
                \synopsys{int fld\_sattr(struct field *, unsigned long)}\\
                If field is NULL use current field.
                Attributes are same as for {\em fld\_sattr()}.

 	\subsection{General functions}
 	    \subsubsection{message} Give message (line 24).
		\synopsys{int message(char *fmt, ...)}

	    \subsubsection{strequ} Compare two strings, but case insensitive. 
		Otherwhise the same functionality as strcmp().
		\synopsys{int strequ(char *s1, char *s2)}

	\subsection{Global variables}
	    Theese two global variables exists for backward compability only, 
	    if current field or current picture is to be referenced a NULL
	    pointer can always be used instead.
	    \subsubsection{current.picture} Allways points to current picture
		(can be NULL).
		\synopsys{struct picture *current.picture}

	    \subsubsection{current.field} Allways points to current field
		(can be NULL).
		\synopsys{struct field *current.field}

\section{How to compile and install CForms}

When you have unpacked the CForms archive you just do cd to the directory
where you unpacked it and change the DEST-variable in the Makefile.src to
where you want CForms installed. Then the {\em Configure} script must run.
After that you should do a 'make' followed by an 'make install'.
Don't make any changes in the Makefile, do it in the Makefile.src and rerun 
Configure instead.

You can also compile the example application in the example subdirectory
by doing 'make example', check it out to see what an application might look
like.

\section{How to compile CForms applications}

Lets say you just installed CForms with DEST set to {\em /usr/local},
that means that the CForms compiler resides in /usr/local/bin, the
cforms include file resides in /usr/local/include and the library
libcforms.a in /usr/local/lib, then this is how to compile a CForms
application:

First you run the CForms compiler, {\em cfc}, on your inputfiles:
    \begin{verbatim}
	cfc form1.frm
	cfc form2.frm
    \end{verbatim}

This will generate the c-code output files, {\em form1.c} and {\em form2.c}.
Those files must now be linked with the cforms linker {\em cfl}, just do:
    \begin{verbatim}
	cfl form1.frm form2.frm
    \end{verbatim}
This will produce the cforms linkage file {\em cforms.c}
What the linker does is simply putting together a list of all modules that
should be used from the application.
Now the system native c-compiler should be used to compile all those files
(including the cforms.c file)
plus all other files that should go along with the application:
    \begin{verbatim}
	cc -o <yourapp> -I/usr/local/include -L/usr/local/lib \
		 cforms.c form1.c form2.c -lcforms -lcurses -lterminfo
    \end{verbatim}
Observe that the -L flag must be there because the cforms library is in
/usr/\-local/\-lib.

Now you should be able to run you application.

\section{CForms formulas in object libraries}

It is possible to use pictures that has previously been compiled into object
libraries, in that case the modules from those libraries must be presented to
the cforms linker and to do this the name of the library module must be known
by the programmer.
The reason only the name has to be known is that the name of the module defines
a global varaible inside the library and {\em cfl} uses only the name of the
module and not the contents.

The first step in making a library is to run {\em cfc} on the forms file, this
produces the c-file. Compile this and put it into a library.

This example shows how the module {\em file\_browser} is put into a library:

\begin{verbatim}
    cfc file_browser.frm
    cc -c -I/usr/local/include file_browser.c
    ar r libfile.a file_browser.o
\end{verbatim}

Now the module is in the library libfile.a, if another application wants to
use pictures from this module it must first  add the text file\_browser.frm
to the argument list of {\em cfl}. Finally the actual library must be linked
with the application.

This example show the application {\em user\_menu} calls upon the
{\em file\_browser} module.
\begin{verbatim}
    cfc user_menu.frm
    cfl user_menu.frm file_browser.frm
    cc -o user_menu user_menu.o -L/usr/local/lib libfile.a \
        -lcforms -lcurses -lterminfo
\end{verbatim}
Also note that even if only one module is to be used the cfl must be
invoked for this single file to generate the {\em cforms.c} file.

\section{Keys}
Theese are the keys that can be used in event routines, note that capital
letter are doubles:
   \begin{tabbing}
    CLEAR: Sent by clear screen or erase key.xx\= \kill
    UNDERSCORE: Underscore	\> PLUS: Plus sign \\
    MINUS: Minus sign		\> AT: At sign \\
    HASH: hash mark		\> DOLLAR: Dollar sign \\
    SLASH: Slash sign		\> ASTERISK: Star \\
    TILDE: Tilde sign		\> BANG: Exclamation mark \\
    EQUAL: Equal sign		\> PERCENT: Precent sign \\
    AMPERSAND: And or Ampersand sign	\> LPAR: Left parentesis \\
    RPAR: Right parentesis	\> LBRACKET: Left bracket \\
    RBRACKET: Right breacket	\> LBRACE: Left brace \\
    RBRACE: Right brace		\> QUOTE: Souble quote \\
    SPACE: Space bar 		\> BLANK: Space bar  \\
    QUESTION: Question mark	\> ESC: Escape  \\
    BS: Backspace 		\> CR: Carriage return  \\
    TAB: Tab 			\> BREAK: break key (unreliable)  \\
    DOWN: Sent by terminal down arrow key \> UP: Sent by terminal up arrow key  \\
    LEFT: Sent by terminal left arrow key \> RIGHT: Sent by terminal right arrow key  \\
    HOME: Sent by home key. 	\> BACKSPACE: Sent by backspace key  \\
    F0 - F20: Function keys	\> DL: Sent by delete line key.  \\
    IL: Sent by insert line. 	\> DC: Sent by delete character key.  \\
    IC: Sent by ins char/enter ins mode key. \> EIC: Sent by rmir or smir in insert mode.  \\
    CLEAR: Sent by clear screen or erase key.\> EOS: Sent by clear-to-end-of-screen key.  \\
    EOL: Sent by clear-to-end-of-line key.\> SF: Sent by scroll-forward/down key  \\
    SR: Sent by scroll-backward/up key\> NPAGE: Sent by next-page key  \\
    PPAGE: Sent by previous-page key\> STAB: Sent by set-tab key  \\
    CTAB: Sent by clear-tab key	\> CATAB: Sent by clear-all-tabs key.  \\
    ENTER: Enter/send 		\> SRESET: soft (partial) reset \\
    RESET: reset or hard reset 	\> PRINT: print or copy  \\
    LL: Sent by home-down key 	\> A1: Upper left of keypad  \\
    A3: Upper right of keypad 	\> B2: Center of keypad  \\
    C1: Lower left of keypad 	\> C3: Lower right of keypad  \\
    BTAB: Back tab key 		\> BEG: beg(inning) key  \\
    CANCEL: cancel key 		\> CLOSE: close key  \\
    COMMAND: cmd (command) key 	\> COPY: copy key  \\
    CREATE: create key 		\> END: end key  \\
    EXIT: exit key 		\> FIND: find key  \\
    HELP: help key 		\> MARK: mark key  \\
    MESSAGE: message key 	\> MOVE: move key  \\
    OPTIONS: options key 	\> PREVIOUS: previous object key  \\
    REDO: redo key 		\> REFERENCE: ref(erence) key  \\
    REFRESH: refresh key 	\> REPLACE: replace key  \\
    RESTART: restart key 	\> RESUME: resume key  \\
    SAVE: save key 		\> SBEG: shifted beginning key  \\
    SCANCEL: shifted cancel key \> SCOMMAND: shifted command key  \\
    SCOPY: shifted copy key 	\> SCREATE: shifted create key  \\
    SDC: shifted delete char key\> SDL: shifted delete line key  \\
    SELECT: select key 		\> SEND: shifted end key  \\
    SEOL: shifted clear line key\> SEXIT: shifted exit key  \\
    SFIND: shifted find key 	\> SHELP: shifted help key  \\
    SHOME: shifted home key 	\> SIC: shifted input key  \\
    SLEFT: shifted left arrow key\> SMESSAGE: shifted message key  \\
    SMOVE: shifted move key 	\> SNEXT: shifted next key  \\
    SOPTIONS: shifted options key \> SPREVIOUS: shifted prev key  \\
    SPRINT: shifted print key 	\> SREDO: shifted redo key  \\
    REPLACE: shifted replace key\> NEXT: next object key \\
    SRIGHT: shifted right arrow	\> SRSUME: shifted resume key \\
    SSAVE: shifted save key	\> SSUSPEND: shifted suspend key \\
    SUNDO: shifted undo key	\> SUSPEND: suspend key \\
    UNDO: Undo key		\> MOUSE: Mouse event \\
    OPEN: open key		\> ANY: Any key \\
    AA - ZZ: Capital letters	\> a - z: lower case characters. \\
    \end{tabbing}
	
\newpage
\tableofcontents

\end{document}
